Loadstar 128 #10/q10.d81/t.128 shell

Text File | 1990-01-01 | 13.7 KB | 357 lines

                     L O A D S T A R    S H E L L   1 2 8

                             by Robert Rockefeller

      The LOADSTAR Shell Utility gives C-128 users the ability to execute
machine-language programs by typing the name of the program, as well as a
RAM disk in bank one RAM in which machine-language and BASIC programs can
be loaded.  Included with the shell program are ten useful utility
programs. Utility programs will execute from the RAM disk very quickly
indeed.

     The shell program uses memory from address $1300 to address $1b00.
Since BASIC program storage starts at address $1c00, this means the shell
is compatible with normal BASIC programs.  However, BASIC programs which
try to load machine-language, or POKE data to memory being used by the
shell will crash the computer.  In our experience the shell is compatible
with the vast majority of BASIC programs.

     The RAM disk starts at the top of RAM bank 1 at address $ff00, and
grows downwards from there. Any RAM which is not being used by the RAM disk
is available to BASIC for storage of strings, variables, and arrays.  The
RAM disk can grow to a maximum size of about 57000 bytes, is protected from
BASIC and cannot be harmed by BASIC programs, except by programs which POKE
data to memory being used by the RAM disk.  However, BASIC programs of this
type are very rare.

    All in all the shell program has a very high degree of compatiblity
with BASIC programs, but will almost certainly crash if used with
commercial machine-language programs such as wordprocessors, paint
programs, etc.

    The shell possesses a feature which will allow you to re-start the
shell after pressing the RESET button.  This is useful when you have
programs in the RAM disk since you won't have to re-load.  To restart just
execute SYS4870 from BASIC, or G 1306 from the monitor.  The shell computes
its own checksum to verify code integrity, then it will compute the RAM
disk checksums.  If the shell checksum is invalid the shell will not
re-start, and you must RUN"SHELL to re-start.  If any of the programs in
the RAM disk are invalid their names will be listed, and they will be
marked invalid so they can't be loaded.  In addition, you will be given the
opportunity to clear the RAM disk.

    Shell utility programs can be loaded into the RAM disk with the LD
utility (see below) then executed by simply typing their names.  BASIC
programs can also be loaded into the RAM disk with LD then RUN by
specifying a device number of 7.  For example, you would type RUN"MAIL
LIST",U7 then type RETURN to execute the program "MAIL LIST".

     If you wish to write your own machine-language programs for use with
the shell you must be aware of several things.  First of all the program
filenames must begin with the letters "COM.".  This is necessary so the
shell can distinguish shell programs from other types of files.  Second of
all, the machine-language programs must be assembled to execute at address
$1c03.  Thirdly, shell machine-language programs must terminate with a RTS
instruction, or by JMPing to address $1303.  Last of all, like BASIC
variables, utility names cannot have a BASIC command embedded in it.  For
example the name "COM.DCLR" would be an invalid name because it has the
command CLR in it.

    As an example, one of the included shell programs named "COM.DL" will
list a BASIC program on disk.  To execute it you merely need to type the
utility name without the "COM." prefix, plus the name of one or more files
you wish to list.  For example, to list a BASIC program named "FILECOPY"
you would type DL "FILECOPY", then type the RETURN key.  If you have more
than one disk drive you can specify a device number by prefixing it to the
filename.  For example, DL "FILECOPY" 9,"RAMDOS" would list "FILECOPY" from
device 8, and "RAMDOS" from device 9.  Filenames need not be enclosed in
quotes except when they contain a BASIC command.  For example, "FILECOPY"
would need to be enclosed in quotes since it contains the BASIC command
COPY.  "RAMDOS" would not necessarily need to be in quotes since it
contains no BASIC command.  However, as a general rule we recommend that
filenames be enclosed in quotes.

    The ten included utility programs are explained below.

"COM.TYPE"

    TYPE displays disk text files on the screen.  Either normal or screen
code files can be displayed.  Screen code files can be specified by using
the +S switch.  PET ASCII files are the default type, but can be specified
using the -S switch.  Examples:

TYPE +S 9,"CODES" -S "TEXT1"

This would display a screen code file "CODES" from device 9, then a PET
ASCII file "TEXT1" from device 8.

TYPE "LETTER"

This would display a PET ASCII file "LETTER" from device 8.

"COM.DUMP"

    DUMP displays disk files on the screen in both hexadecimal and text
format.  Either normal or screen code files can be displayed.  Screen code
files can be specified by using the +S switch.  PET ASCII files are the
default type, but can be specified by using the -S switch.  Examples:

DUMP +S 9,"CODES" -S "TEXT1"

This would display a screen code file "CODES" from device 9, then a PET
ASCII file "TEXT1" from device 8.

DUMP "LETTER"

This would display a PET ASCII file "LETTER" from device 8.

"COM.DL"

    DL displays BASIC programs from disk on the screen.  Example:

DL 9,"DATABASE" "SUBS"

This would display a BASIC program "DATABASE" from device 9, then the file
"SUBS" from device 8.

"COM.VAR"

    VAR displays all defined variables and their values.  This is mostly
useful during BASIC programming.  Example: VAR

"COM.ARY"

    ARY can do two things.  ARY alone or ARY LIST lists the names and sizes
of all arrays.  ARY followed by an array name will display the array on the
screen.  This is mostly useful during BASIC programming.  Examples:

ARY

This would display the names and sizes of all arrays.

ARY B

This would display the floating point array B.

ARY CE$

This would display the string array CE$

"COM.LD"

    LD is provided to load files into the bank 1 RAM disk.  Simply follow
the LD command with the names of files you wish loaded.  See "COM.SUBMIT"
also.  An alternative form LD CLR removes the RAM disk from memory.
Examples:

LD "COM.DIR"

Load "COM.DIR" into the RAM disk

LD "COM.TYPE" "COM.DUMP" "COM.DL"

Load "COM.TYPE", "COM.DUMP", and "COM.DL" into the RAM disk

"COM.DIR"

     DIR is provided to display a directory of the files stored in the RAM
disk.  Example:

DIR

Displays RAM disk directory.

"COM.COM"

     COM is provided to specify the search order for COM files.  The shell
always checks the RAM disk first.  Normally device 8 is then searched.
However up to three disk devices can be specified to be searched in any
order.  Examples:

COM 9 8

Specify that device 9 be searched after the RAM disk, then device 8.

COM 8 9 10

Specify that device 8 be searched after the RAM disk, then device 9, then
device 10.

COM 8

Specify that device 8 only be searched after the RAM disk.

"COM.SUBMIT"

     SUBMIT is possibly the most versatile and useful command of all.  It
allows you to execute lists of commands stored on disk just as if they had
been typed at the keyboard.  Literally any command that you can type in can
be executed from a disk file.  SUBMIT is useful when you find yourself
entering the same sequence of commands over and over.  You can enter these
commands into a disk file and type one command to execute the disk file.
For example, if you fiad yourself regularly using LD to load several
utilities into the RAM disk, ysu can save typing by putting the LD command
in a SUBMIT file.  If each line in a SUBMIT file begins with a line number,
the lines will be merged into the BASIC program text.

     SUBMIT works almost exactly like "SUBMIT.COM" does under CP/M for
those familiar with CP/M.  SUBMIT files must have a "SUB." prefix.
"SUB.LDALL" is an example of a SUBMIT filename.  Follow the SUBMIT command
with the name of the file you wish to execute.  For example, SUBMIT "LDALL"
would execute the file "SUB.LDALL".

     You can pass parameters to SUBMIT files when they are executed.  Each
parameter is scanned and a textual substitution takes place.  $1 is
replaced by the first parameter, $2 is replaced by the second parameter,
etc.  Up to 9 parameters may be passed to a SUBMIT file.  For example if a
SUBMIT file "SUB.REN" contained the following lines:

SCRATCH "COM.$1"

RENAME "BIN.$1" TO "COM.$1"

and you entered the following command,

SUBMIT REN ARY

the word ARY would be substituted in every case for $1 producing:

SCRATCH "COM.ARY"

RENAME "BIN.ARY" TO "COM.ARY"

This is an example of a SUBMIT file that was actually used by the author in
the preparation of these utilities.

     If you pass more parameters than called for in the SUBMIT file, the
extra parameters are ignored.  If you pass fewer parameters than called for
in a SUBMIT file, some parameters will be replaced by the null string.  For
example, if we have a SUBMIT file "SUB.AS" containing ASM $1 $2 $3, and we
execute SUBMIT AS DEBUG, this would expand into ASM DEBUG.  The $2 and $3
are replaced with literally nothing.  To include an actual dollar sign $ in
a SUBMIT file just precede it with another dollar sign.  For example, $$ in
a SUBMIT file would be expanded into simply $ when the file is executed.

    SUBMIT files can be created in three ways.  If you wish to create a
SUBMIT file consisting of a BASIC subroutine that can be merged, just DOPEN
a file to disk, use CMD to set output to the file, then LIST the subroutine
to disk, use PRINT# to clear the output channel, then CLOSE the file.  To
create a SUBMIT file of commands, just DOPEN a file to disk, PRINT# the
commands to the disk file, then CLOSE the file.  Alternately, you can
create SUBMIT files with "COM.EDT", the full-screen programmer's text
editor that's on this side of LOADSTAR.

"COM.PC"

    This utility is a simple programmer's calculator with 28 functions,
three memories, and which can display in four radices, decimal,
hexadecimal, binary, and character.  The calculator is an RPN (Reverse
Polish Notation) stack-oriented calculator as opposed to the more common
algebraic calculators.  You enter numbers onto a stack, then perform
operations on the stack.  You enter a number by typing it then typing the
RETURN or ENTER keys.  For example, typing 5.543 RETURN would place 5.543
on the stack.  A number is also automatically entered when you type an
operation key like * (multiplication).  For example, here's how to multiply
5 times 3. type:
5 RETURN 3 *

     Note that the * operator is entered after the numbers it operates on.
This notation was invented by a Polish mathematician and is known as
Reverse Polish Notation.  The two top stack positions are special since all
arithmetic and logical operations are performed on one or both of these
entries.  The top entry is known as the X register, and the second entry is
the Y register, hereafter referred to simply as X and Y.

     When you are entering a number a solid cursor is displayed on the top
stack entry, indicating input mode.  During input mode you can type DEL to
delete the last character entered.  Typing RETURN terminates input mode and
puts the number entered on the stack.  Typing DEL when no cursor is
displayed deletes the top stack entry.  Typing RETURN when no cursor is
displayed duplicates the top entry.  You can type the CLR key to clear the
stack and memories.

     If an error occurs during an operation, such as OVERFLOW, DIVISION BY
ZERO, etc., the error message will be displayed at the bottom of the
calculator, and you must type the ESC key to clear the error message.  The
functions are listed below.  In order to perform a function you must type a
SHIFT key and the indicated key simultaneously.  For example, to set
hexadecimal radix mode type a SHIFT key and the H key simultaneously.
Setting CAPS LOCK is useful in all modes except character radix mode.

RUN STOP

    Exit the calculator.  Return to BASIC.

D  Set decimal radix.  During number entry you can enter the keys 0..9, the
Decimal point ., and e or E to indicate exponentiation.  After entering e
or E you may type the - sign to indicate a negative exponent.  Except for
this one special case, typing - computes Y - X.

H  Set hexadecimal radix.  You can enter the keys 0..9 and a..f.

B  Set binary radix.  You can enter the keys 0 or 1 only.

C  Set character radix.  You can enter any character as a number.  In order
to execute a function you must type the ESC key first.  For example to
switch to hexadecimal radix type the ESC key and release it, then type a
SHIFT key and the H key simultaneously.

P  Pick operation.  Copy a number to the top of the stack.  The stack
entries are numbered from 0 (the top) to 7 (the bottom).  After typing P
type a digit corresponding to the entry you wish to copy.

R  Roll operation.  Move a number to the top of the stack.  The stack
entries are numbered from 0 (the top) to 7 (the bottom).  After typing R
type a digit corresponding to the entry you wish to move.

W  Swap operation.  Swap the contents of X and Y.

F  Fetch. Copy a memory register to the top of the stack.  After typing F
type a digit 0, 1, or 2 corresponding to the memory register you wish to
fetch.

U  Put. Copy X to a memory register.  After typing U type a digit 0, 1, or
2 corresponding to the memory register you wish to store X to.

I  Int.  Remove the fractional part of X.

G  Negate. Change the sign of X.

A  Compute the absolute value of X.

L  Compute the natural logarithm of X.

Q  Compute the square root of X.

X  Compute the value of e^X, where e=2.71828183.

O  Compute the cosine of X.

S  Compute the sine of X.

N  Compute the tangent of X.

T  Compute the arctangent of X.

+  Compute Y + X.

-  Compute Y - X.

*  Compute Y * X.

/  Compute Y / X.

M  Modulus.  Compute the remainder of Y / X.

^  Compute Y to the power of X.

&  Compute Y AND X.

!  Compute Y EXCLUSIVE-OR X.

{SHIFT--}  Compute Y OR X.

RR
                             **** End of Text ****